ENVI::AddExtension
The ENVI::AddExtension method allows a Toolbox Extension to rename the entry in the Extensions folder, and optionally to place the Toolbox entry inside a user-defined folder structure witin the Toolbox or the ENVI menu.
If you want the Toolbox to display the renamed entry in the current session, issue the .RESET_SESSION command after calling the AddExtension method.
Note: This method should not be used inside of batch programs or while interacting with ENVI at the IDL command line. This method should only be included in an EXTENSIONS_INIT routine.
Example
The following example demonstrates a scenario when you would use the UVALUE keyword. You may want to use the same Toobox extension but with different results, depending on which item the user selects. This example adds two new Toolbox extensions: Brighten Data and Darken Data.
Here, you select a dataset and spatial or spectral subset (using ENVI's Select Input dialog). Depending on whether UVALUE is set to 'brighten'
or 'darken'
, it adds or subtracts a DN value of 50 from each of the selected pixels.
- Copy and paste the following code into a new file in IDL, and save the file as
brightenordarkendata.pro
. - Issue the following commands to generate a SAVE file. If
brightenordarkendata.pro
is not in the current directory of the IDL path, provide the full path in the .COMPILE command. The SAVE file will be saved to the current directory unless you specify a full path in which to save. - Close IDL.
- Move the file
brightenordarkendata.pro.sav
intoinstall_dir\ENVIxx\extensions
. If you do not have write permission to that directory, you can define an ENVI_EXTENSIONS environment variable that points to the directory that contains the SAVE file. - Launch ENVI from the Start menu.
- In the Toolbox
Extensions
folder, notice that the extensions Brighten Data and Darken Data are now listed. Double-click Brighten Data. - When prompted for the input file, select
install_dir\ENVIxx\data\qb_boulder_msi
. - When prompted for the output file, enter a valid filename and path.
- When the script finishes executing, the new file displays.
PRO brightenordarkendata_extensions_init
COMPILE_OPT IDL2
; Get the current application
e = ENVI(/CURRENT)
e.AddExtension, 'Brighten Data', 'brightenordarkendata', UVALUE='brighten'
e.AddExtension, 'Darken Data', 'brightenordarkendata', UVALUE='darken'
END
PRO brightenordarkendata, event
COMPILE_OPT IDL2
CATCH, err
IF err NE 0 THEN BEGIN
CATCH, /CANCEL
void = DIALOG_MESSAGE('Could not perform operation. An error occurred:' + $
!ERROR_STATE.msg, /ERROR)
MESSAGE, /RESET
RETURN
ENDIF
e = ENVI(/CURRENT)
WIDGET_CONTROL, event.ID, GET_UVALUE = uvalue
; Select a raster.
raster = e.UI.SelectInputData(TITLE = 'Select a file to '+uvalue+'.', $
/RASTER, BANDS = bands, SUB_RECT = subrect, /DISABLE_NO_DATA)
; Get the data and subrect.
data = raster.GetData()
; Select a new raster to save.
newfile = DIALOG_PICKFILE(/WRITE)
; Now brighten or darken the data.
IF uvalue EQ 'brighten' THEN addvalue = 50 ELSE addvalue = -50
CASE raster.INTERLEAVE of
'bsq': data[subrect[0]:subrect[2], subrect[1]:subrect[3], bands] += addvalue
'bil': data[subrect[0]:subrect[2], bands, subrect[1]:subrect[3]] += addvalue
'bip': data[bands, subrect[0]:subrect[2], subrect[1]:subrect[3]] += addvalue
ENDCASE
; Create the new raster.
newraster = ENVIRaster(data, URI=newFile)
; Save and display the new raster.
newraster.save
view = e.GetView()
layer = view.CreateLayer(newraster)
END
.RESET_SESSION
.COMPILE brightenordarkendata.pro
RESOLVE_ALL, /CONTINUE_ON_ERROR, SKIP_ROUTINES='ENVI'
SAVE, FILENAME = 'brightenordarkendata.sav', /ROUTINES
To place these extensions in the ENVI menu (under Display > Contrast) instead of the Toolbox, modify the AddExtension method calls as follows:
e.AddExtension, 'Brighten Data', 'brightenordarkendata', $
UVALUE='brighten', /MENU, PATH='Display/Contrast'
e.AddExtension, 'Darken Data', 'brightenordarkendata', $
UVALUE='darken', /MENU, PATH='Display/Contrast'
Then follow Steps 2 through 5 above to update the extension and to re-start ENVI.
Syntax
ENVI.AddExtension, Name, Routine [, Keywords=value]
Arguments
Name
A scalar string denoting the name that will appear in the Toolbox.
Routine
A scalar string denoting the IDL procedure that will be run when the Toolbox item is double-clicked.
Keywords
Keywords are applied only during the initial creation of the object.
AFTER
Use this keyword in combination with the MENU keyword to indicate the menu position that the new item should follow. This only applies to the final position in the menu hierarchy. For example, suppose that you have an extension named Routine 2 that should follow Routine 1. Set the AFTER keyword as follows:
e.AddExtension, 'Routine 1', 'myroutine1.pro', /MENU, $
PATH='Display/MyTools'
e.AddExtension, 'Routine 2', 'myroutine2.pro', /MENU, $
PATH='Display/MyTools', AFTER='Routine 1'
You cannot use this keyword in combination with the BEFORE keyword. Set this keyword to one of the following values:
- Integer: If you set this keyword to an integer (beginning with 0 for the first menu item), the new item will appear after the item in that position.
- String: The new item will appear after the item that you specify. Strings are not case-sensitive.
BEFORE
Use this keyword in combination with the MENU keyword to indicate the menu position that the new item should precede. This only applies to the final position in the menu hierarchy. You cannot use this keyword in combination with the AFTER keyword. Set this keyword to one of the following values:
- Integer: If you set this keyword to an integer (beginning with 0 for the first menu item), the new item will appear before the item in that position.
- String: The new item will appear before the item that you specify. Strings are not case-sensitive.
ERROR
Set this keyword to a named variable that will contain any error message issued during execution of this routine. If no error occurs, the ERROR variable will be set to a null string (''
). If an error occurs and the routine is a function, then the function result will be undefined.
When this keyword is not set and an error occurs, ENVI returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine. See IDL Help for more information on !ERROR_STATE and CATCH.
See Manage Errors for more information on error handling in ENVI programming.
MENU
Set this keyword to place the Toolbox item in the ENVI menu instead of the Toolbox. You cannot add extensions to the top-level menu, only under an existing menu item.
PATH
A scalar string denoting the tree structure, under the Extensions folder, in which the Toolbox item will appear. If PATH is not specified, the item is added directly to the end of the Extensions folder. Multiple subfolders may be specified by adding the forward slash character between folder names (for example, My Routines/Statistics
). If a folder does not currently exist, it will be created automatically.
When used in conjunction with the MENU keyword, the path denotes an optional sub-menu under which the menu button will be added. You can add multiple sub-menus by using the forward slash character (/) between their names.
SEPARATOR
Set this keyword (in conjunction with the MENU keyword) to place a separator line above the new item in the menu. A separator line cannot appear above the first item in a menu.
TOOLTIP
A scalar string denoting a description for this entry that will be displayed when the user hovers over the Toolbox item. This keyword will be ignored if the extension is added to the ENVI menu.
UVALUE
Set this keyword to a value containing information you want to maintain about the new Toolbox item. This value is passed through the extension's widget event, which can be passed in as the first argument to the toolbox extension's main procedure. You can retrieve the UVALUE from the event with the following command:
WIDGET_CONTROL, event.id, GET_UVALUE = uvalue
See Example for a typical scenario that uses UVALUE.
Version History
ENVI 5 |
Introduced |
ENVI 5.0.2 |
Added AFTER, BEFORE, MENU, and SEPARATOR keywords |
ENVI 5.7 | Added TOOLTIP keyword |
API Version
4.2